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ABOUT THIS CHAPTER 


The Printing Manager is a set of RAM-based routines and data types that allow 
you to use standard QuickDraw routines to print text or graphics on a printer. 
The Printing Manager calls the Printer Driver, a device driver in RAM. It also 
includes low-level calls to the Printer Driver so that you can implement 
alternate, low-level printing routines. 


You should already be familiar with the following: 


the Resource Manager 

QuickDraw 

dialogs, as described in the Dialog Manager chapter 

the Device Manager, if you're interested in writing your 
own Printer Driver 

e Apple LaserWriter Reference 


eoeee 
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ABOUT THE PRINTING MANAGER 


The Printing Manager isn't in the Macintosh ROM; to access the Printing Manager 
routines, you must link with an object file or files provided as part of your 
development system. 


The Macintosh user prints a document by choosing the Print command from the 
application's File menu; a dialog then requests information such as the print 
quality and number of copies. The Page Setup command in the File menu lets the 
user specify formatting information, such as the page size, that rarely needs to 
be changed and is saved with the document. The Printing Manager provides your 
application with two standard dialogs for obtaining Page Setup and Print 
information. The user can also print directly from the Finder by selecting one 
or more documents and choosing Print from the Finder's File menu; the Print 
dialog is then applied to all of the documents selected. 


The Printing Manager is designed so that your application doesn't have to be 
concerned with what kind of printer is connected to the Macintosh; you call the 
same printing routines, regardless of the printer. This printer independence is 
possible because the actual printing code (which is different for different 
printers) is contained in a separate printer resource file on the user's disk. 
The printer resource file contains a device driver, called the Printer Driver, 
that communicates between the Printing Manager and the printer. 


The user installs a new printer with the Choose Printer desk accessory, which 
gives the Printing Manager a new printer resource file. This process is 
transparent to your application, and your application should not make any 
assumptions about the printer type. 


Figure 1 shows the flow of control for printing on the Macintosh. 


You define the image to be printed by using a printing grafPort, a QuickDraw 
grafPort with additional fields that customize it for printing: 


TYPE TPPrPort = “TPrPort; 
TPrPort = RECORD 
gPort: GrafPort; {grafPort to draw in} 
{more fields for internal use} 
END; 
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Figure 1—Printing Overrie¥ 
Figure 1-Printing Overview 


The Printing Manager gives you a printing grafPort when you open a document for 
printing. You then print text and graphics by drawing into this port with 
QuickDraw, just as if you were drawing on the screen. The Printing Manager 
installs its own versions of QuickDraw's low-level drawing routines in the 
printing grafPort, causing your higher-level QuickDraw calls to drive the 
printer instead of drawing on the screen. 


Warning: You should not try to do your own customization of QuickDraw 
routines in the printing grafPort unless you're sure of what 
you're doing. 


The Printing Manager has been enhanced and made easier to use through these 
changes: 


e Its code has been moved from a linked file into the 256K ROM. 

e New low-level printer control calls have been added, in the form 
of new predefined parameter constants for PrCtlCall. 

¢ A generic procedure called PrGeneral now lets your application 
perform several advanced printer configuration tasks. 
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PRINT RECORDS AND DIALOGS 


To format and print a document, your application must know the following: 


¢ the dimensions of the printable area of the page 

¢ if the application must calculate the margins, the size of the physical 
sheet of paper and the printer's vertical and horizontal resolution 

¢ which printing method is being used (draft or spool, explained below) 


This information is contained in a data structure called a print record. The 
Printing Manager fills in the entire print record for you. Information that the 
user can specify is set through two standard dialogs. 


The style dialog should be presented when the user selects the application's 
Page Setup command from the File menu. It lets the user specify any options that 
affect the page dimensions, that is, the information you need for formatting the 
document to match the printer. Figure 2 shows the standard style dialog for the 
Imagewriter printer. 


LaserWriter Page Setup 
Paper: @ US Letter © A4Letter 


OUS Legal OBS Letter ©|_Tabloid Cancel 
Reduce or Printer Effects: 
Enlarge: [roo jg 


[x] Font Substitution? 
Orientation >] Text Smoothing? 
>] Graphics Smoothing? 
>] Faster Bitmap Printing? 


Figure 2—The Style Dialog 
Figure 2—The Style Dialog 


The job dialog should be presented when the user chooses to start printing with 
the Print command. It requests information about how to print the document this 
time, such as the print quality (for printers that offer a choice of 
resolutions), the type of paper feed (such as fanfold or cut-sheet), the range 
of pages to print, and the number of copies. Figure 3 shows the standard job 
dialog for the Imagewriter. 
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Figure 3-The Job Dialog 
Figure 3—The Job Dialog 


Note: The dialogs shown in Figures 2 and 3 are examples only; the 
actual content of these dialogs is customized for each printer. 


Print records are referred to by handles. Their structure is as follows: 


TYPE THPrint = *TPPrint; 

TPPrint = *TPrint; 

TPrint = RECORD 
iPrVersion: INTEGER; {Printing Manager version} 
prinfo: TPrinfo; {printer information subrecord} 
rPaper: Rect; {paper rectangle} 
prstl: TPrStl; {additional device information} 
prinfoPT: TPrinfo; {used internally} 
prXInfo: TPrXInfo; {additional device information} 
prJob: TPrJjob; {job subrecord} 
printx: ARRAY[1..19] OF INTEGER {not used} 

END; 


Warning: Your application should not change the data in the print record—be 
sure to use the standard dialogs for setting this information. The 
only fields you'll need to set directly are some containing optional 
information in the job subrecord (explained below). Attempting to set 
other values directly in the print record can produce unexpected 

results. 


IPrVersion identifies the version of the Printing Manager that initialized this 
print record. If you try to use a print record that's invalid for the current 
version of the Printing Manager or for the currently installed printer, the 
Printing Manager will correct the record by filling it with default values. 


The other fields of the print record are discussed in separate sections below. 


Note: Whenever you save a document, you should write an appropriate print 
record in the document's resource file. This lets the document 
"remember" its own printing parameters for use the next time it's 
printed. 
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The Printer Information Subrecord 


The printer information subrecord (field prinfo of the print record) gives you 
the information needed for page composition. It's defined as follows: 


TYPE TPrinfo = RECORD 
iDev: INTEGER; {used internally} 
iVRes: INTEGER; {vertical resolution of printer} 
iHRes: INTEGER; {horizontal resolution of printer} 
rPage: Rect {page rectangle} 
END; 


RPage is the page rectangle, representing the boundaries of the printable page: 
The printing grafPort's boundary rectangle, portRect, and clipRgn are set to 
this rectangle. Its top left corner always has coordinates (0,0); the 
coordinates of the bottom right corner give the maximum page height and width 
attainable on the given printer, in dots. Typically these are slightly less than 
the physical dimensions of the paper, because of the printer's mechanical 
limitations. RPage is set as a result of the style dialog. 


The rPage rectangle is inside the paper rectangle, specified by the rPaper field 
of the print record. RPaper gives the physical paper size, defined in the same 
coordinate system as rPage (see Figure 4). Thus the top left coordinates of the 
paper rectangle are typically negative and its bottom right coordinates are 
greater than those of the page rectangle. 


IVRes and iHRes give the printer's vertical and horizontal resolution in dots 
per inch. Thus, if you divide the width of rPage by iHRes, you get the width of 
the page rectangle in inches. 


The Job Subrecord 


The job subrecord (field prjJob of the print record) contains information about a 
particular printing job. Its contents are set as a result of the job dialog. 
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Figure 4—Page and Paper Rectangles 
Figure 4—Page and Paper Rectangles 


The job subrecord is defined as follows: 


TYPE TPrjJob = RECORD 
iFstPage: 
iLstPage: 
iCopies: 


bjJDocLoop: 


fFromUsr: 


pIdleProc: 
pFileName: 


iFileVol: 


bFileVers: 


bJobx: 
END; 


INTEGER; 
INTEGER; 
INTEGER; 
SignedByte; 
BOOLEAN; 
ProcPtr; 
StringPtr; 
INTEGER; 
SignedByte; 
SignedByte 


{first page to print} 
{last page to print} 
{number of copies} 
{printing method} 
{used internally} 
{background procedure} 
{spool file name} 


{spool file volume reference number} 


{spool file version number} 
{used internally} 


BJDocLoop designates the printing method that the Printing Manager will use. It 
will be one of the following predefined constants: 


CONST bDraftLoop 
bSpoolLoop 


0; 
1; 


{draft printing} 
{spool printing} 


Draft printing means that the document will be printed immediately. Spool 


printing means that printing may be deferred: 


The Printing Manager writes out a 


representation of the document's printed image to a disk file (or possibly to 
memory); this information is then converted into a bit image and printed. For 
details about the printing methods, see the "Methods of Printing" section below. 
The Printing Manager sets the bJDocLoop field; your application should not 


change it. 
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IFstPage and iLstPage designate the first and last pages to be printed. These 
page numbers are relative to the first page counted by the Printing Manager. The 
Printing Manager knows nothing about any page numbering placed by an application 
within a document. 


ICopies is the number of copies to print. The Printing Manager automatically 
handles multiple copies for spool printing or for printing on the LaserWriter. 
Your application only needs this number for draft printing on the Imagewriter. 


PIdleProc is a pointer to the background procedure (explained below) for this 
printing operation. In a newly initialized print record this field is set to 
NIL, designating the default background procedure, which just polls the keyboard 
and cancels further printing if the user types Command-period. You can install a 
background procedure of your own by storing a pointer to your procedure directly 
into the pIdleProc field. 


For spool printing, your application may optionally provide a spool file name, 
volume reference number, and version number (described in the File Manager 
chapter): 


¢ PFileName is the name of the spool file. This field is initialized to 
NIL, and generally not changed by the application. NIL denotes the 
default file name (normally ‘Print File') stored in the printer resource 
file. 

e JIFileVol is the volume reference number of the spool file. This field 
is initialized to 0, representing the default volume. You can use the 
File Manager function SetVol to change the default volume, or you can 
override the default setting by storing directly into this field. 

¢ BFileVers is the version number of the spool file, initialized to 0. 


Additional Device Information 


The prStl and prXInfo fields of the print record provide device information that 
your application may need to refer to. 


The prStl field of the print record is defined as follows: 


TYPE TPrStl = RECORD 
wDev: INTEGER; {high byte specifies device} 
{more fields for internal use} 
END; 


The high-order byte of the wDev field indicates which printer is currently 
selected. A value of 0 indicates the Macintosh screen; other values are 
reserved for future use. The low-order byte of wDev is used internally. 


The prXInfo field of the print record is defined as follows: 


TYPE TPrXInfo = RECORD 
iRowBytes: INTEGER; {used internally} 
iBandV: INTEGER; {used internally} 
iBandH: INTEGER; {used internally} 
iDevBytes: INTEGER; {size of buffer} 
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{more fields for internal use} 
END; 


IDevBytes is the number of bytes of memory required as a buffer for spool 
printing. (You need this information only if you choose to allocate your own 
buffer. ) 
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METHODS OF PRINTING 


There are two basic methods of printing documents: draft and spool. The 
Printing Manager determines which method to use; the two methods are implemented 
in different ways for different printers. 


In draft printing, your QuickDraw calls are converted directly into command 
codes the printer understands, which are then immediately used to drive the 
printer: 


e On the Imagewriter, draft printing is used for printing quick, 
low-quality drafts of text documents that are printed straight 
down the page from top to bottom and left to right. 

e On the LaserWriter, draft printing is used to obtain high-quality 
output. (This typically requires 15K bytes of memory for your data 
and printing code.) 


Spool printing is a two-stage process. First, the Printing Manager writes out 

("spools") a representation of your document's printed image to a disk file or 
to memory. This information is then converted into a bit image and printed. On 
the Imagewriter, spool printing is used for standard or high-quality printing. 


Spooling and printing are two separate stages because of memory considerations: 
Spooling a document takes only about 3K bytes of memory, but may require large 
portions of your application's code and data in memory; printing the spooled 
document typically requires from 20K to 40K for the printing code, buffers, and 
fonts, but most of your application's code and data are no Longer needed. 
Normally you'll make your printing code a separate program segment, so you can 
swap the rest of your code and data out of memory during printing and swap it 
back in after you're finished (see the Segment Loader chapter). 


Note: This chapter frequently refers to spool files, although there may be 
cases when the document is spooled to memory. This difference will be 
transparent to the application. 


Note: The internal format of spool files is private to the Printing Manager 
and may vary from one printer to another. This means that spool files 
destined for one printer can't be printed on another. In spool files for 
the Imagewriter, each page is stored as a QuickDraw picture. It's 
envisioned that most other printers will use this same approach, but 
there may be exceptions. Spool files can be identified by their file 
type ('PFIL') and creator ('PSYS'). File type and creator are discussed 
in the Finder Interface chapter. 
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BACKGROUND PROCESSING 


As mentioned above, the job subrecord includes a pointer, pIdleProc, to an 
optional background procedure to be run whenever the Printing Manager has 
directed output to the printer and is waiting for the printer to finish. The 
background procedure takes no parameters and returns no result; the Printing 
Manager simply runs it at every opportunity. 


If you don't designate a background procedure, the Printing Manager uses a 
default procedure for canceling printing: The default procedure just polls the 
keyboard and sets a Printing Manager error code if the user types Command- 
period. If you use this option, you should display a dialog box during printing 
to inform the user that the Command-period option is available. 


Note: If you designate a background procedure, you must set pIdleProc after 
presenting the dialogs, validating the print record, and initializing 
the printing grafPort: The routines that perform these operations 
reset pIdleProc to NIL. 


Warning: If you write your own background procedure, you must be careful to 
avoid a number of subtle concurrency problems that can arise. For 
instance, if the background procedure uses QuickDraw, it must be 
sure to restore the printing grafPort as the current port before 
returning. It's particularly important not to attempt any printing 
from within the background procedure: The Printing Manager is not 
reentrant! If you use a background procedure that runs your 
application concurrently with printing, it should disable all menu 
items having to do with printing, such as Page Setup and Print. 
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USING THE PRINTING MANAGER 


To use the Printing Manager, you must first initialize QuickDraw, the Font 
Manager, the Window Manager, the Menu Manager, TextEdit, and the Dialog Manager. 
The first Printing Manager routine to call is PrOpen; the last routine to call 
is PrClose. 


Before you can print a document, you need a valid print record. You can either 
use an existing print record (for instance, one saved with a document), or 
initialize one by calling PrintDefault or PrValidate. If you use an existing 
print record, be sure to call PrValidate to make sure it's valid for the current 
version of the Printing Manager and for the currently installed printer. To 
create a new print record, you must first create a handle to it with the Memory 
Manager function NewHandle, as follows: 


prRecHdl := THPrint (NewHandle(SIZEOF(TPrint) ) ) 
Print record information is obtained via the style and job dialogs: 


« Call PrStlDialog when the user chooses the Page Setup commmand, to get 
the page dimensions. From the rPage field of the printer information 
subrecord, you can then determine where page breaks will be in the 
document. You can show rulers and margins correctly by using the 
information in the iVRes, iHRes, and rPaper fields. 

e Call PrjJobDialog when the user chooses the Print commmand, to get the 
specific information about that printing job, such as the page range and 
number of copies. 


You can apply the results of one job dialog to several documents (when printing 
from the Finder, for example) by calling PrJobMerge. 


After getting the job information, you should immediately print the document. 


The Printing Loop 
To print a document, you call the following procedures: 


1. PrOpenDoc, which returns a printing grafPort that's set up for draft 
or spool printing (depending on the bJDocLoop field of the job subrecord) 
2. PrOpenPage, which starts each new page (reinitializing the grafPort) 
3. QuickDraw routines, for drawing the page in the printing grafPort 
created by PrOpenDoc 
4. PrClosePage, which terminates the page 
5. PrCloseDoc, at the end of the entire document, to close the printing 
grafPort 


Each page is either printed immediately (draft printing) or written to the disk 
or to memory (spool printing). You should test to see whether spooling was done, 
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and if so, print the spooled document: First, swap as much of your program out 
of memory as you can (see the Segment Loader chapter), and then call PrPicFile. 


It's a good idea to call PrError after each Printing Manager call, to check for 
any errors. To cancel a printing operation in progress, use PrSetError. If an 
error occurs and you cancel printing (or if the user aborts printing), be sure 
to exit normally from the printing loop so that all files are closed properly; 
that is, be sure that every PrOpenPage is matched by a PrClosePage and PrOpenDoc 
is matched by PrCloseDoc. 


To sum up, your application's printing loop will typically use the following 
basic format for printing: 


myPrPort := PrOpenDoc(prRecHdl,NIL,NIL); {open printing grafPort} 


FOR pg := 1 TO myPgCount DO {page loop: ALL pages of document} 
IF PrError = noErr 
THEN 
BEGIN 


PrOpenPage(myPrPort,NIL) ; {start new page} 
IF PrError = noErr 


THEN MyDrawingProc(pg); {draw page with QuickDraw} 
PrClosePage(myPrPort) ; fend current page} 
END; 
PrCloseDoc(myPrPort) ; {close printing grafPort} 
IF prRecHdl**.prjJob.bJDocLoop = bSpoolLoop AND PrError = noErr 
THEN 
BEGIN 
MySwapOutProc; {swap out code and data} 
PrPicFile(prRecHdl,NIL,NIL,NIL,myStRec); {print spooled document} 
END; 


IF PrError <> noErr THEN MyPrErrAlertProc {report any errors} 


Note an important assumption in this example: The MyDrawingProc procedure must 
be able to determine the page boundaries without stepping through each page of 
the document. 


Although spool printing may not be supported on all printers, you must be sure 
to include PrPicFile in your printing code, as shown above. The application 
should make no assumptions about the printing method. 


Note: The maximum number of pages in a spool file is defined by the 
following constant: 


CONST iPFMaxPgs = 128; 


If you need to print more than 128 pages at one time, just repeat the printing 
loop (without calling PrValidate, PrStlDialog, or PrJjobDialog). 


Printing a Specified Range of Pages 
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The above example loops through every page of the document, regardless of which 
pages the user has selected; the Printing Manager draws each page but actually 
prints only the pages from iFstPage to iLstPage. 


If you know the page boundaries in the document, it's much faster to loop 
through only the specified pages. You can do this by saving the values of 
iFstPage and iLstPage and then changing these fields in the print record: For 
example, to print pages 20 to 25, you would set iFstPage to 1 and iLstPage to 6 
(or greater) and then begin printing at your page 20. You could implement this 
for all cases as follows: 


myFirst := prRecHdl**.prJjob.iFstPage; {save requested page numbers} 
myLast := prRecHdl**.prJob.iLstPage; 

prRecHdl**.prjob.iFstPage := 1; {print "all" pages in loop} 
prRecHdl**.prjob.iLstPage := 9999; 


FOR pg := myFirst TO myLast DO {page loop: requested pages only} 
a {print as in first example} 


Remember that iFstPage and iLstPage are relative to the first page counted by 
the Printing Manager. The Printing Manager counts one page each time PrOpenPage 
is called; the count begins at 1. 


Using QuickDraw for Printing 
When drawing to the printing grafPort, you should note the following: 


¢ With each new page, you get a completely reinitialized grafPort, so 
you'll need to reset font information and other grafPort characteristics 
as desired. 

« Don't make calls that don't do anything on the printer. For example, 
erase operations are quite time-consuming and normally aren't needed 
on the printer. 

« Don't use clipping to select text to be printed. There are a number of 
subtle differences between how text appears on the screen and how it 
appears on the printer; you can't count on knowing the exact dimensions 
of the rectangle occupied by the text. 

¢ Don't use fixed-width fonts to align columns. Since spacing gets 
adjusted on the printer, you should explicitly move the pen to where 
you want it. 


For printing to the LaserWriter, you'll need to observe the following 
limitations: 


Regions aren't supported; try to simulate them with polygons. 
Clipping regions should be limited to rectangles. 

"Invert" routines aren't supported. 

Copy is the only transfer mode supported for all objects except text 
and bit images. For text, Bic is also supported. For bit images, the 
only transfer mode not supported is Xor. 

e Using SetOrigin within the printing loop is supported, but you should 
refer to Technical Note #183 for implementation details. 


eoeee 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE PRINTING MANAGER ¢ 16 of 43 


eeeClick on the X-Ref button, and refer to Technical Note #183.¢ee 


For more information about optimizing your printing code for the LaserWriter, 
see the Apple LaserWriter Reference. 


Printing From the Finder 


The Macintosh user can choose to print from the Finder as well as from an 
application. Your application should support both alternatives. 


To print a document from the Finder, the user selects the document's icon and 
chooses the Print command from the File menu. Note that the user can select more 
than one document, or even a document and an application, which means that the 
application must verify that it can print the document before proceeding. When 
the Print command is chosen, the Finder starts up the application, and passes 
information to it indicating that the document is to be printed rather than 
opened (see the Segment Loader chapter). Your application should then do the 
following, preferably without going through its entire startup sequence: 


1. Call PrjobDialog. (If the user selected more than one document, you 
can use PrjJobMerge to apply one job dialog to all of the documents. ) 
2. Print the document(s). 
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PRINTING MANAGER ROUTINES 


This section describes the high-level Printing Manager routines; low-level 
routines are described below in the section "The Printer Driver". 


Assembly-language note: There are no trap macros for these routines. To 
print from assembly language, call these Pascal 
routines from your program. 


Initialization and Termination 
PROCEDURE PrOpen; [Not in ROM] 


PrOpen prepares the Printing Manager for use. It opens the Printer Driver and 
the printer resource file. If either of these is missing, or if the printer 
resource file isn't properly formed, PrOpen will do nothing, and PrError will 
return a Resource Manager result code. 


PROCEDURE PrClose; [Not in ROM] 
PrClose releases the memory used by the Printing Manager. It closes the printer 


resource file, allowing the file's resource map to be removed from memory. It 
doesn't close the Printer Driver. 


Print Records and Dialogs 
PROCEDURE PrintDefault (hPrint: THPrint); [Not in ROM] 


PrintDefault fills the fields of the specified print record with default values 
that are stored in the printer resource file. HPrint is a handle to the record, 
which may be a new print record that you've just allocated with NewHandle or an 
existing one (from a document, for example). 


FUNCTION PrValidate (hPrint: THPrint) : BOOLEAN; [Not in ROM] 


PrValidate checks the contents of the specified print record for compatibility 
with the current version of the Printing Manager and with the currently 
installed printer. If the record is valid, the function returns FALSE (no 
change); if invalid, the record is adjusted to the default values stored in the 
printer resource file, and the function returns TRUE. 


PrValidate also makes sure all the information in the print record is internally 
self-consistent and updates the print record as necessary. These changes do not 
affect the function's Boolean result. 


Warning: You should never call PrValidate (or PrStlDialog or PrJobDialog, 
which call it) between pages of a document. 
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FUNCTION PrStlDialog (hPrint: THPrint) : BOOLEAN; [Not in ROM] 


PrStlDialog conducts a style dialog with the user to determine the page 
dimensions and other information needed for page setup. The initial settings 
displayed in the dialog box are taken from the most recent print record. If the 
user confirms the dialog, the results of the dialog are saved in the specified 
print record, PrValidate is called, and the function returns TRUE. Otherwise, 
the print record is left unchanged and the function returns FALSE. 


Note: If the print record was taken from a document, you should update its 
contents in the document's resource file if PrStlDialog returns TRUE. 
This makes the results of the style dialog "stick" to the document. 


FUNCTION PrjJobDialog (hPrint: THPrint) : BOOLEAN; [Not in ROM] 


PrjJobDialog conducts a job dialog with the user to determine the print quality, 
range of pages to print, and so on. The initial settings displayed in the dialog 
box are taken from the printer resource file, where they were remembered from 
the previous job (with the exception of the page range, set to all, and the 
copies, set to l). 


If the user confirms the dialog, both the print record and the printer resource 
file are updated, PrValidate is called, and the function returns TRUE. 
Otherwise, the print record and printer resource file are left unchanged and the 
function returns FALSE. 


Note: Since the job dialog is associated with the Print command, you should 
proceed with the requested printing operation if PrjJobDialog returns 
TRUE. 


PROCEDURE PrJobMerge (hPrintSrc,hPrintDst: THPrint); [Not in ROM] 


PrjobMerge first calls PrValidate for each of the given print records. It then 
copies all of the information set as a result of a job dialog from hPrintSrc to 
hPrintDst. Finally, it makes sure that all the fields of hPrintDst are 
internally self-consistent. 


PrjJobMerge allows you to conduct a job dialog just once and then copy the job 
information to several print records, which means that you can print several 
documents with one dialog. This is useful when printing from the Finder. 


Printing 


FUNCTION PrOpenDoc (hPrint: THPrint; pPrPort: TPPrPort; 
plOBuf: Ptr) : TPPrPort; [Not in ROM] 


PrOpenDoc initializes a printing grafPort for use in printing a document, makes 
it the current port, and returns a pointer to it. 


HPrint is a handle to the print record for this printing operation; you should 
already have validated this print record. 
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Depending on the setting of the bJDocLoop field in the job subrecord, the 
printing grafPort will be set up for draft or spool printing. For spool 
printing, the spool file's name, volume reference number, and version number are 
taken from the job subrecord. 


PPrPort and pIOBuf are normally NIL. PPrPort is a pointer to the printing 
grafPort; if it's NIL, PrOpenDoc allocates a new printing grafPort in the heap. 
Similarly, pIOBuf points to an area of memory to be used as an input/output 
buffer; if it's NIL, PrOpenDoc uses the volume buffer for the spool file's 
volume. If you allocate your own buffer, it must be 522 bytes long. 


Note: These parameters are provided because the printing grafPort and 
input/output buffer are both nonrelocatable objects; to avoid 
fragmenting the heap, you may want to allocate them yourself. 


You must balance every call to PrOpenDoc with a call to PrCloseDoc. 
PROCEDURE PrOpenPage (pPrPort: TPPrPort; pPageFrame: TPRect); [Not in ROM] 


PrOpenPage begins a new page. The page is printed only if it falls within the 
page range given in the job subrecord. 


For spool printing, the pPageFrame parameter is used for scaling. It points to a 
rectangle to be used as the QuickDraw picture frame for this page: 


TYPE TPRect = “Rect; 


When you print the spooled document, this rectangle will be scaled (with the 
QuickDraw procedure DrawPicture) to coincide with the rPage rectangle in the 
printer information subrecord. Unless you want the printout to be scaled, you 
should set pPageFrame to NIL—this uses the rPage rectangle as the picture frame, 
so that the page will be printed with no scaling. 


Warning: Don't call the QuickDraw function OpenPicture while a page is open 
(after a call to PrOpenPage and before the following PrClosePage). 
You can, however, call DrawPicture at any time. 


Warning: The printing grafPort is completely reinitialized by PrOpenPage. 
Therefore, you must set grafPort features such as the font and 
font size for every page that you draw. 
You must balance every call to PrOpenPage with a call to PrClosePage. 
PROCEDURE PrClosePage (pPrPort: TPPrPort); [Not in ROM] 
PrClosePage finishes the printing of the current page. It lets the Printing 
Manager know that you're finished with this page, so that it can do whatever is 
required for the current printer and printing method. 
PROCEDURE PrCloseDoc (pPrPort: TPPrPort); [Not in ROM] 
PrCloseDoc closes the printing grafPort. For draft printing, PrCloseDoc ends the 


printing job. For spool printing, PrCloseDoc ends the spooling process: The 
spooled document must now be printed. Before printing it, call PrError to find 
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out whether spooling succeeded; if it did, you should swap out as much code as 
possible and then call PrPicFile. 


PROCEDURE PrPicFile (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr; 
pDevBuf: Ptr; VAR prStatus: TPrStatus); [Not in ROM] 


PrPicFile prints a spooled document. If spool printing is being used, your 
application should normally call PrPicFile after PrCloseDoc. 


HPrint is a handle to the print record for this printing job. The spool file's 
name, volume reference number, and version number are taken from the job 
subrecord of this print record. After printing is successfully completed, the 
Printing Manager deletes the spool file from the disk. 


You'll normally pass NIL for pPrPort, pIOBuf, and pDevBuf. PPrPort is a pointer 

to the printing grafPort for this operation; if it's NIL, PrPicFile allocates a 

new printing grafPort in the heap. Similarly, pIOBuf points to an area of memory 
to be used as an input /output buffer for reading the spool file; if 

it's NIL, PrPicFile uses the volume buffer for the spool file's volume. PDevBuf 

points to a device-dependent buffer; if NIL, PrPicFile allocates a buffer in the 
heap. 


Note: If you provide your own storage for pDevBuf, it has to be big enough 
to hold the number of bytes indicated by the iDevBytes field of the 
PrXInfo subrecord. 


Warning: Be sure not to pass, in pPrPort, a pointer to the same printing 
grafPort you received from PrOpenDoc. If that port was allocated 
by PrOpenDoc itself (that is, if the pPrPort parameter to PrOpenDoc 
was NIL), then PrCloseDoc will have disposed of the port, making 
your pointer to it invalid. Of course, if you earlier provided your 
own storage to PrOpenDoc, there's no reason you can't use the same 
storage again for PrPicFile. 


The prStatus parameter is a printer status record that PrPicFile will use to 
report on its progress: 


TYPE TPrStatus = RECORD 


iTotPages: INTEGER; {number of pages in spool file} 
iCurPage: INTEGER; {page being printed} 
iTotCopies: INTEGER; {number of copies requested} 
iCurCopy: INTEGER; {copy being printed} 
iTotBands: INTEGER; {used internally} 
iCurBand: INTEGER; {used internally} 
fPgDirty: BOOLEAN; {TRUE if started printing page} 
fImaging: BOOLEAN; {used internally} 
hPrint: THPrint; {print record} 
pPrPort: TPPrPort; {printing grafPort} 
hPic: PicHandle {used internally} 

END; 


The fPgDirty field is TRUE if anything has already been printed on the current 
page, FALSE if not. 
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Your background procedure (if any) can use this record to monitor the state of 
the printing operation. 


Error Handling 
FUNCTION PrError : INTEGER; [Not in ROM] 


PrError returns the result code left by the last Printing Manager routine. Some 
possible result codes are: 


CONST noErr = 0; {no error} 
iPrSavPFil = -1; {saving print file} 
controlErr = —-17; {unimplemented control instruction} 
il0Abort = -27; {I/O error} 
iMemFullErr = —108; {not enough room in heap zone} 
iPrAbort = 128; {application or user requested abort} 


{ The following result codes are LaserWriter-specific } 


—4101; Printer not found or closed } 
—4100; Connection just closed } 
—4099; Write request too big } 


{ 
{ 
{ 
—4098; { Request already active } 
—4097; { Bad connection refnum } 
—4096; {No free CCBs (Connect Control Blocks) available } 
-8133; { PostScript error occurred during transmission } 

{ of data to printer. Most often caused by a bug } 

{ in the PostScript code being downloaded. } 

{ Timeout occured. This error is returned when } 

{ no data has been sent to the printer for 2 } 

{ minutes. Usually caused by extremely long } 

{ imaging times. } 


—8132; 


ControlErr is returned by the Device Manager. Other Operating System or Toolbox 
result codes may also be returned; a list of all result codes is given in 
Appendix A. 


Assembly-language note: The current result code is contained in the global 
variable PrintErr. 


PROCEDURE PrSetError (iErr: INTEGER); [Not in ROM] 


PrSetError stores the specified value into the global variable where the 
Printing Manager keeps its result code. This procedure is used for canceling a 
printing operation in progress. To do this, call: 


IF PrError <> noErr THEN PrSetError(iPrAbort) 


Assembly-language note: You can achieve the same effect as PrSetError by 
storing directly into the global variable PrintErr. 
You shouldn't, however, store into this variable 
if it already contains a nonzero value. 
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CALLING THE PRINTING MANAGER IN ROM 


ALL the Printing Manager routines are now accessible through the single trap 


_PrGlue, available in System file version 4.1 and later. 


To use trap calls with 


all System file versions, link your application to PRGlue, available in the MPW 


2.0 file Interface.o. 


Here are the Printing Manager trap calls as they appear in the Pascal interface: 


PROCEDURE PrOpen; 
PROCEDURE PrClose; 
PROCEDURE PrintDefault (hPrint: THPrint); 
FUNCTION PrValidate (hPrint: THPrint) : Boolean; 
FUNCTION PrStlDialog (hPrint: THPrint) : Boolean; 
FUNCTION PrJobDialog (hPrint: THPrint) : Boolean; 
PROCEDURE PrJobMerge (hPrintSrc, hPrintDst: THPrint); 
FUNCTION PrOpenDoc (hPrint: THPrint; pPrPort: TPPrPort; 
plOBuf : Ptr): TPPrPort; 
PROCEDURE PrCloseDoc (pPrPort: TPPrPort) ; 
PROCEDURE PrOpenPage (pPrPort: TPPrPort; pPageFrame: TPRect); 
PROCEDURE PrClosePage (pPrPort: TPPrPort); 
PROCEDURE PrPicFile (hPrint: THPrint; pPrPort: TPPrPort; plOBuf: Ptr; 
pDevBuf : Ptr; VAR PrStatus: TPrStatus) ; 
FUNCTION PrError: Integer; 
PROCEDURE PrSetError (iErr: Integer); 
PROCEDURE PrDrvrOpen; 
PROCEDURE PrDrvrClose; 
PROCEDURE PrctlCall (iWhichCtl: Integer; lParaml, lParam2, lParam3: LongInt); 
FUNCTION PrDrvrDCE: Handle; 
FUNCTION PrDrvrVers: Integer; 


You can still call Printing Manager routines with the formats given in the 
previous section by using one of the following interface files: 


e PrintTraps.p for Pascal 

e PrintTraps.h for C 

¢ PrintTraps.a for assembly language 
Assembly-language note: You can invoke each of the Printing Manager routines 
by pushing a longint called a routine selector on the 
stack and then executing the PrGlue trap ($A8FD). 
The routine selectors are the following: 


PrOpen EQU $C8000000 
PrClose EQU $D0000000 
PrintDefault EQU $20040480 
PrValidate EQU $52040498 
PrStlDialog EQU $2A040484 
PrjJobDialog EQU $32040488 
PrjobMerge EQU $5804089C 
PrOpenDoc EQU $04000C00 
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PrCloseDoc EQU $08000484 
PrOpenPage EQU $10000808 
PrClosePage  EQU $1800040C 
PrPicFile EQU $60051480 
PrError EQU $BA000000 
PrSetError EQU $C0000200 
PrDrvrOpen EQU $80000000 
PrDrvrClose EQU $88000000 
PrctlCall EQU $AQ0000E00 
PrDrvrDCE EQU $94000000 
PrDrvrVers EQU $9A000000 
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PRGENERAL 


The Printing Manager has been expanded to include a new procedure called 
PrGeneral. It provides advanced, special-purpose features, intended to solve 
specific problems for those applications that need them. You can use PrGeneral 
with version 2.5 and later of the ImageWriter driver and version 4.0 and later 
of the LaserWriter driver. The Pascal declaration of PrGeneral is 


PROCEDURE PrGeneral (pData: Ptr); 


The pData parameter is a pointer to a data block. The structure of the data 
block is declared as follows: 


TGnlData = RECORD 
{1st 8 bytes are common for all PrGeneral calls); 
i0pCode: Integer; {input} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
{more fields here, depending on particular call} 


END; 

The first field in the TGnlData record is a 2-byte opcode, iOpCode, which acts 
somewhat like a routine selector. The currently available opcodes are these: 

¢ GetRslData (get resolution data) : i0pCode = 4 

« SetRsl (set resolution) : i0pCode = 5 

« DraftBits (bitmaps in draft mode) : i0pCode = 6 

¢ NoDraftBits (no bitmaps in draft mode) : i0pCode = 7 

« GetRotn (get rotation) : i0pCode = 8 


GetRslData and SetRsl allow the application to find out what physical 
resolutions the printer supports, and then specify a supported resolution. 
DraftBits and noDraftBits invoke a new feature of the ImageWriter, allowing 
bitmaps (imaged via CopyBits) to be printed in draft mode. GetRotn lets an 
application know whether landscape orientation has been selected. These 
routines are described in the next sections. 


The second field in the TGnlData record is the error result, iError, returned by 
the print code. This error only reflects error conditions that occur during 
the PrGeneral call. For example, if you use an opcode that isn't implemented in 
a particular printer driver then you will get an OpNotImpl error. Here are the 
error codes: 


CONST 
NoErr = 0; {no error} 
NoSuchRsl = 1; {the resolution you chose isn't available} 
OpNotImpl = 2; {the driver doesn't support this opcode} 


After calling PrGeneral you should always check PrError. If NoErr is returned, 
then you can proceed. If ResNotFound is returned, then the current printer 
driver doesn't support PrGeneral and you should proceed appropriately. 
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IError is followed by a four byte reserved field. The contents of the rest of 
the data block depends on the opcode that the application uses. 


GetRslData 


GetRslData (i0pCode = 4) returns a record that lets the application know what 
resolutions are supported by the current printer. The application can then use 
SetRsl to tell the printer driver which one it will use. These calls introduce 
a good deal of complexity into your application's code, and should be used only 
when necessary. 


This is the format of the input data block for the GetRslData call: 


TRslRg = RECORD {used in TGetRslBlk} 
iMin: Integer; {0 if printer supports only discrete resolutions} 
iMax: Integer; {0 if printer supports only discrete resolutions} 
END; 


TRslRec = RECORD {used in TGetRslBlk} 
iXRsl: Integer; {a discrete, physical X resolution} 
iYRsl: Integer; {a discrete, physical Y resolution} 


END; 
TGetRslBlk = RECORD {data block for GetRslData call} 
i0pCode: Integer; {input; = getRslData0p} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
iRgType: Integer; {output; version number} 
XRslRg: TRslRg; {output; range of X resolutions} 
YRslRg: TRslRg; {output; range of Y resolutions} 
iRslRecCnt: Integer; {output; how many RslRecs follow} 


rgRslRec: ARRAY[1..27] OF TRslRec; {output; number filled } 
{ depends on printer type} 
END; 


The iRgType field is much like a version number; it determines the 
interpretation of the data that follows. An iRgType value of 1 applies both to 
the LaserwWriter and to the ImageWriter. 


For variable-resolution printers like the LaserWriter, the resolution range 
fields XRslRg and YRslRg express the ranges of values to which the X and Y 
resolutions can be set. For discrete-resolution printers like the ImageWriter, 
the values in the resolution range fields are zero. 


Note: In general, X and Y in these records are the horizontal and vertical 
directions of the printer, not the document. In "landscape" 
orientation, X is horizontal on the printer but vertical on the document. 


After the resolution range information there is a word which gives the number of 
resolution records that contain information. These records indicate the 
physical resolutions at which the printer can actually print dots. Each 
resolution record gives an X value and a Y value. 
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When you call PrGeneral, use the following data block: 


Oplode = 4 1 word 
Lo 


RamgeType = 1 1 word 


x Resolution Faluge: Sirois 
Tin = 0, Max = 0 


Y Resolution Rams: re 
wa 


min = 0, max = 0) 


Resolution Record Count = 0 1 word 


Eesolution Record #1: 2 apd 
H=0,Y7=0 


Eesolution Record #2..27 


Figure 5-—Data Block for PrGeneral 
Figure 5—Data Block for PrGeneral 


Here is the data block returned by the LaserWriter: 
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OpCode = 4 1 word 
Error Tode (0 = okay] 1 word 


RangeT ype = 1 1 word 


H Eesolution Range: Seiea 


Min= 72, Max = 1500 


Y Eesolution Range: 2 ward 
Min = 72, Max = 1500 


Resolution Record Count = 1 1 word 


Fecolution Record #1: 


H= 300, ¥ = 300 ane 


Figure 6—Data Block Retumed by LaserWriter 


Figure 6—Data Block Returned by the LaserWriter 
Notice that all the resolution range numbers are the same for this printer. 
There is only one resolution record, which gives the physical X and Y 
resolutions of the printer (300 x 300). 


Below is the data block returned by the ImageWriter. 
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Opole = 4 1 word 
Error Code (0 = okay] 1 word 


FangeType = 1 1 word 


H Resolution Range: Banas 
min = 0, max = 0 


¥ Resolution Range: 2 worils 
min = 0, max = 0 
Fesolution Record Count = 4 1 worl 
Resolution Record #1: 
He 72, ¥=72 2 words 
Resolution Record #2: 
Hs idd, ¥ = 144 eewanls 
Resolution Record #3: 
He 80,¥=72 a wont 
Resolution Record #4: Sie 


H= 160, ¥ = 144 


Figure 7—Data Block Retomed by Imaze Writer 
Figure 7—Data Block Returned by the ImageWriter 


ALL the resolution range values are zero, because only discrete resolutions can 
be specified for the ImageWriter. There are four resolution records giving 
these discrete physical resolutions. 


GetRslData always returns the same information for a particular printer type—it 
is not dependent on what the user does or on printer configuration information. 


SetRsl 


SetRsl (i0pCode = 5) is used to specify the desired imaging resolution, after 
using GetRslData to determine a workable pair of values. Below is the format of 
the data block: 


TSetRslBlk = RECORD {data block for SetRsl call} 
i0pCode: Integer; {input; = setRslOp} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
hPrint: THPrint; f{input; handle to a valid print record} 
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iXRslL: Integer; {input; desired X resolution} 
iYRsL: Integer; {input; desired Y resolution} 
END; 


The hPrint parameter contains the handle of a print record that has previously 
been passed to PrValidate. If the call executes successfully, the print record 
is updated with the new resolution; the data block comes back with 0 for the 
error and is otherwise unchanged. If the desired resolution is not supported, 
the error is set to noSuchRsl and the resolution fields are set to the 
printer's default resolution 


You can undo the effect of a previous call to SetRsl by making another call that 
specifies an unsupported resolution (such as 0 x 0), forcing the default 
resolution. 


DraftBits 


DraftBits (i0pCode = 6) is implemented on both the ImageWriter and the 
LaserWriter. On the LaserWriter it does nothing, because the LaserWriter is 
always in draft mode and can always print bitmaps. Here is the format of the 
data block: 


TDftBitsBlk = RECORD {data block for DraftBits and } 
{ NoDraftBits calls} 
i0pCode: Integer; {input; = draftBitsOp or noDraftBitsOp} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
hPrint: THPrint; f{input; handle to a valid print record} 
END; 


The hPrint parameter contains the handle of a print record that has previously 
been passed to PrValidate. 


This call forces draft-mode (immediate) printing, and will allow bitmaps to be 
printed via CopyBits calls. The virtue of this is that you avoid spooling 
large masses of bitmap data onto the disk, and you also get better performance. 


The following restrictions apply: 


« This call should be made before bringing up the print dialog boxes 
because it affects their appearance. On the ImageWriter, calling 
DraftBits disables the landscape icon in the Style dialog, and the 
Best, Faster, and Draft buttons in the Job dialog box. 

e If the printer does not support draft mode, already prints bitmaps 
in draft mode, or does not print bitmaps at all, this call does nothing. 

¢ Only text and bitmaps can be printed. 

¢ As in the normal draft mode, landscape format is not allowed. 

e Everything on the page must be strictly Y-sorted; that is, no reverse 
paper motion between one string or bitmap and the next. This means 
you can't have two or more objects (text or bitmaps) side by side; the 
top boundary of each object must be no higher than the bottom of the 
preceding object. 
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The last restriction is important. If you violate it, you will not like the 
results. However, if you want two or more bitmaps side by side, you can combine 
them into one before calling CopyBits to print the result. Similarly, if you 
are just printing bitmaps you can rotate them yourself to achieve landscape 
printing. 


NoDraftBits 


NoDraftBits (i0pCode = 7) is implemented on both the ImageWriter and the 
LaserWriter. On the LaserWriter it does nothing, since the LaserWriter is 
always in draft mode and can always print bitmaps. The format of the data block 
is the same as that for the DraftBits call. This call cancels the effect of any 
preceding DraftBits call. If there was no preceding DraftBits call, or the 
printer does not support draft-mode printing anyway, this call does nothing. 


GetRotn 


GetRotn (i0pCode = 8) is implemented on the ImageWriter and LaserWriter. Here 
is the format of the data block: 


TGetRotnBlk = RECORD {data block for GetRotn call} 
i0pCode: Integer; {input; = getRotnOp} 
iError: Integer; {output} 
LlReserved: LongInt; {reserved for future use} 
hPrint: THPrint; {input; handle to a valid } 
{ print record} 
flandscape: Boolean; f{output; Boolean flag} 
bXtra: SignedByte; {reserved} 
END; 


The hPrint parameter contains a handle to a print record that has previously 
been passed to PrValidate. 


If landscape orientation is selected in the print record, then fLandscape is 
true. 


Using PrGeneral 


SetRsl and DraftBits calls may require the print code to suppress certain 
options in the Style and/or Job dialog boxes, therefore they should always be 
called before any call to the Style or Job dialogs. An application might use 
PrGeneral as follows: 


¢ Get a new print record by calling PrintDefault, or take an existing 
one from a document and call PrValidate on it. 

e Call GetRsltData to find out what the printer is capable of, and decide 
what resolution to use. Check PrError to be sure the PrGeneral call 
is supported on this version of the print code; if the error is 
ResNotFound, you have older print code and must print accordingly. 
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But if the PrError return is 0, proceed as follows: 
e Call SetRslt with the print record and the desired resolution if you wish. 
« Call DraftBits to invoke the printing of bitmaps in draft mode if you wish. 


If you call either SetRsl or DraftBits, you should do so before the user sees 
either of the printing dialog boxes. 
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THE PRINTER DRIVER 


The Printing Manager provides a high-level interface that interprets QuickDraw 
commands for printing; it also provides a low-level interface that lets you 
directly access the Printer Driver. 


Note: You should not use the high-level and low-level calls together. 


The Printer Driver is the device driver that communicates with a printer. You 
only need to read this section if you're interested in low-level printing or 
writing your own device driver. For more information, see the Device Manager 
chapter. 


The printer resource file for each type of printer includes a device driver for 
that printer. When the user chooses a printer, the printer's device driver 
becomes the active Printer Driver. 


You can communicate with the Printer Driver via the following low-level 
routines: 


e PrDrvrOpen opens the Printer Driver; it remains open until you 
call PrDrvrClose. 
e PrCtlCall enables you to perform low-level printing operations 
such as bit map printing and direct streaming of text to the printer. 
e PrDrvrVers tells you the version number of the Printer Driver. 
e PrDrvrDCE gets a handle to the driver's device control entry. 


Low-Level Driver Access Routines 


The routines in this section are used for communicating directly with the 
Printer Driver. 


PROCEDURE PrDrvrOpen; [Not in ROM] 
PrDrvrOpen opens the Printer Driver, reading it into memory if necessary. 
PROCEDURE PrDrvrClose; [Not in ROM] 


PrDrvrClose closes the Printer Driver, releasing the memory it occupies. 
(Notice that PrClose doesn't close the Printer Driver. ) 


PROCEDURE PrctlCall (iWhichCtl: INTEGER; lParaml,lParam2,lParam3: LONGINT); 
[Not in ROM] 


PrCtlCall calls the Printer Driver's control routine. The iWhichCtl parameter 
identifies the operation to perform. The following values are predefined: 


CONST iPrBitsCtl 
iPrIOctl 


4; {bit map printing} 
5; {text streaming} 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE PRINTING MANAGER ¢ 33 of 43 


iPrDevCtl = 7; {printer control} 


These operations are described in detail in the following sections of this 
chapter. The meanings of the lParam1, lParam2, and lParam3 parameters depend on 
the operation. 


Note: Advanced programmers: If you're making a direct Device Manager 
Control call, iWhichCtl will be the csCode parameter, and lParaml1, 
lParam2, and lParam3 will be csParam, csParam+4, and csParam+8. 

FUNCTION PrDrvrDCE : Handle; [Not in ROM] 

PrDrvrDCE returns a handle to the Printer Driver's device control entry. 


FUNCTION PrDrvrVers : INTEGER; [Not in ROM] 


PrDrvrVers returns the version number of the Printer Driver in the system 
resource file. 


The version number of the Printing Manager is available as the predefined 
constant iPrRelease. You may want to compare the result of PrDrvrVers with 
iPrRelease to see if the Printer Driver in the resource file is the most recent 
version. 


Printer Control 


The iPrDevCtl parameter to PrCtlCall is used for several printer control 
Operations. The high-order word of the lParaml parameter specifies the operation 
to perform: 


CONST 

iPrBitsCtl = 4; {the Bitmap Print Proc's ctl number} 

UScreenBits = $00000000; {the Bitmap Print Proc's Screen Bitmap param} 

lPaintBits = $00000001; {the Bitmap Print Proc's Paint (sq pix) param} 

lHiScreenBits = $00000002; {the Bitmap Print Proc's Screen Bitmap param} 

LHiPaintBits = $00000003; {the Bitmap Print Proc's Paint (sq pix) param} 

iPrIOCtl =.5% {the Raw Byte IO Proc's ctl number} 

iPrEvtctl = 6; {the PrEvent Proc's ctl number; use with Sony } 
{ printers and one of these CParams:} 

LPrEvtAll = $0002FFFD; {PrEvent Proc's CParam for the whole screen} 

LPrEvtTop = $Q0001FFFD {PrEvent Proc's CParam for the top window} 

iPrDevCtl = 5 {the PrDevCtl Proc's ctl number} 

LPrReset = $00010000; {OBSOLETE: Use lLPrDocOpen instead} 

LPrDocOpen = $00010000; {alias for reset} 

LPrPageEnd = $00020000; {OBSOLETE: Use LPrPageClose instead} 

lPrPageClose = $00020000; {alias for end page} 

lPrLineFeed = $00030000; {the PrDevCtl Proc's CParam for paper advance} 

LPrLFStd = $Q003FFFF; {the PrDevCtl Proc's CParam for std paper adv} 

lPrPageOpen = $00040000; {the PrDevCtl Proc's CParam for PageOpen} 

LPrDocClose = $00050000; {the PrDevCtl Proc's CParam for DocClose} 


Other values that may be shown in the interface file are used only by the 
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Macintosh system. The low-order word of lParaml may specify additional 
information. The lParam2 and lParam3 parameters should always be 0. 


Before starting to print, use 


PrctlCall (iPrDevCtl, lPrDocOpen, 0,0); 
PrctlCall (iPrDevCtl, lPrPageOpen, 0, Q); 


to reset the printer to its standard initial state. This call should be made 
only once per document. You can also specify the number of copies to make in the 
low-order byte of this parameter; for example, a value of $00010002 specifies 
two copies. 


The lPrLineFeed and 1lPrLFStd parameters allow you to achieve the effect of 
carriage returns and line feeds in a printer-independent way: 


e LPrLineFeed specifies a carriage return only (with a line feed of 0). 
¢ 1UPrLFStd causes a carriage return and advances the paper by 1/6 inch 
(the standard "CR LF" sequence). 


You can also specify the exact number of dots the paper advances in the low- 
order word of the lParaml parameter. For example, a value of $00030008 for 
lParaml causes a carriage return and advances the paper eight dots. 


You should use these methods instead of sending carriage returns and line feeds 
directly to the printer. 


The call 


PrctlCall (iPrDevCtl, lPrPageClose, 0, Q); 
PrctlCall (iPrDevCtl, lPrDocClose, 0, Q); 


does whatever is appropriate for the given printer at the end of each page, such 
as sending a form feed character and advancing past the paper fold. You should 
use this call instead of just sending a form feed yourself. 


Bit Map Printing 


To send all or part of a QuickDraw bit map directly to the printer, use 
PrctlCall(iPrBitsCtl, pBitMap, pPortRect, LControl) 


The pBitMap parameter is a pointer to a QuickDraw bit map; pPortRect is a 
pointer to the rectangle to be printed, in the coordinates of the printing 
grafPort. 

LControl should be one of the following predefined constants: 


CONST UScreenBits 
LPaintBits 


0; {default for printer} 
1; {square dots (72 by 72)} 


The Imagewriter, in standard resolution, normally prints rectangular dots that 
are taller than they are wide (80 dots per inch horizontally by 72 vertically). 
Since the Macintosh 128K and 512K screen has square pixels (approximately 72 per 
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inch both horizontally and vertically), lPaintBits gives a truer reproduction of 
the screen, although printing is somewhat slower. 


On the LaserWriter, lControl should always be set to lPaintBits. 


Putting all this together, you can print the entire screen at the default 
setting with 


PrctlCall(iPrBitsCtl, ORD(@screenBits) , 
ORD(@screenBits.bounds) , \ScreenBits) 


To print the contents of a single window in square dots, use 


PrctlCall(iPrBitsCtl, ORD(@theWindow’.portBits), 
ORD (@theWindow*.portRect) , LPaintBits) 


Text Streaming 


Text streaming is useful for fast printing of text when speed is more important 
than fancy formatting or visual fidelity. It gives you full access to the 
printer's native text facilities (such as control or escape sequences for 
boldface, italic, underlining, or condensed or extended type), but makes no use 
of QuickDraw. 


You can send a stream of characters (including control and escape sequences) 
directly to the printer with 


PrctlCall(iPrIOCtl, pBuf, LBufCount,0) 


The pBuf parameter is a pointer to the beginning of the text. The low-order word 
of ltBufCount is the number of bytes to transfer; the high-order word must be 0. 


Warning: Relying on specific printer capabilities and control sequences will 
make your application printer-dependent. You can use iPrDevCtl to 
perform form feeds and line feeds in a printer-independent way. 


Note: Advanced programmers who need more information about sending commands 
directly to the LaserWriter should see Macintosh Technical Notes and 
the Apple LaserWriter Reference. 
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SUMMARY OF THE PRINTING MANAGER 


Constants 


CONST 


{ Printing methods } 


bDraftLoop 
bSpoolLoop 


0; {draft printing} 
1; {spool printing} 


{ Maximum number of pages in a spool file } 


iPFMaxPgs 


{ Result codes } 


noErr 
iPrSavPFil 
controlErr 
iI0Abort 
iMemFullErr 
iPrAbort 


{ The following 


128; 


0; {no error} 
-1; {saving spool file} 
-17; {unimplemented control instruction} 
—27; {I/0 abort error} 
—108; {not enough room in heap zone} 
128; {application or user requested abort} 


result codes are LaserWriter-specific } 


—4101; { 
—4100; 
—4099; 
—4098; 
—4097; 
—4096; 
—8133; 


1 
{ 
{ 
{ 
{ 
{ 
{ 
sf 
—8132; { 
{ 
{ 
{ 


{ PrCtlCall parameters } 


iPrBitsCtl 
LScreenBits 
LPaintBits 
LHiScreenBits 
LHiPaintBits 
iPrIOctl 
iPrEvtctl 


4; 
$00000000; 
$00000001; 
$00000002; 
$00000003; 
5; 
6; 


Printer not found or closed } 

Connection just closed } 

Write request too big } 

Request already active } 

Bad connection refnum } 

No free CCBs (Connect Control Blocks) available } 
PostScript error occurred during transmission } 
of data to printer. Most often caused by a bug } 
in the PostScript code being downloaded. } 
Timeout occured. This error is returned when } 
no data has been sent to the printer for 2 } 
minutes. Usually caused by extremely long } 
imaging times. } 


{the Bitmap Print Proc's ctl number} 

{the Bitmap Print Proc's Screen Bitmap param} 
{the Bitmap Print Proc's Paint (sq pix) param} 
{the Bitmap Print Proc's Screen Bitmap param} 
{the Bitmap Print Proc's Paint (sq pix) param} 
{the Raw Byte IO Proc's ctl number} 

{the PrEvent Proc's ctl number; use with Sony } 
{ printers and one of these CParams: } 
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LPrEvtAll = $0002FFFD; {PrEvent Proc's CParam for the whole screen} 
LPrEvtTop = $Q0001FFFD 4{PrEvent Proc's CParam for the top window} 
iPrDevCtl =f {the PrDevCtl Proc's ctl number} 

LPrReset = $00010000; {OBSOLETE: Use LPrDocOpen instead} 

LPrDocOpen = $00010000; {alias for reset} 

LPrPageEnd = $00020000; {OBSOLETE: Use lPrPageClose instead} 
lPrPageClose = $00020000; {alias for end page} 

lPrLineFeed = $00030000; {the PrDevCtl Proc's CParam for paper advance} 
LPrLFStd = $Q003FFFF; {the PrDevCtl Proc's CParam for std paper adv} 
lPrPageOpen = $00040000; {the PrDevCtl Proc's CParam for PageOpen} 
LPrDocClose = $00050000; {the PrDevCtl Proc's CParam for DocClose} 


{PrGeneral i0pCode values} 


GetRslData = 4; {get resolution data} 
SetRsl =:'53 {set resolution} 

DraftBits = 6; {bitmaps in draft mode} 
NoDraftBits = 7: {no bitmaps in draft mode} 
GetRotn = 8; {get rotation} 


{PrGeneral error codes} 


NoErr = 0; {no error} 
NoSuchRsl a1 {the resolution you chose isn't available} 
OpNotImpl = 2; {the driver doesn't support this opcode} 
Data Types 
TYPE 


TPPrPort = “TPrPort; 
TPrPort = RECORD 


gPort: GrafPort; {grafPort to draw in} 
{more fields for internal use} 
END; 
THPrint = *“TPPrint; 
TPPrint = *TPrint; 
TPrint = RECORD 
iPrVersion: INTEGER; {Printing Manager version} 
prinfo: TPrinfo; {printer information subrecord} 
rPaper: Rect; {paper rectangle} 
prstl: TPrStl; {additional device information} 
prinfoPT: TPrinfo; {used internally} 
prXInfo: TPrXInfo; {additional device information} 
prJob: TPrJjob; {job subrecord} 
printx: ARRAY[1..19] OF INTEGER {not used} 


END; 


TPrinfo = RECORD 
iDev: INTEGER; {used internally} 
iVRes: INTEGER; {vertical resolution of printer} 
iHRes: INTEGER; {horizontal resolution of printer} 
rPage: Rect {page rectangle} 
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END; 


TPrjob = RECORD 


iFstPage: INTEGER; {first page to print} 
iLstPage: INTEGER; {last page to print} 
iCopies: INTEGER; {number of copies} 
bjJDocLoop: SignedByte; {printing method} 
fFromusr: BOOLEAN; {used internally} 
pIdleProc: ProcPtr; {background procedure} 
pFileName: StringPtr; {spool file name} 
iFileVolL: INTEGER; {spool file volume reference number} 
bFileVers: SignedByte; {spool file version number} 
bJobx: SignedByte {used internally} 
END; 
TPrStl = RECORD 
wDev: INTEGER; {high byte specifies device} 
{more fields for internal use} 
END; 
TPrXInfo = RECORD 
iRowBytes: INTEGER; {used internally} 
iBandV: INTEGER; {used internally} 
iBandH: INTEGER; {used internally} 
iDevBytes: INTEGER; {size of buffer} 
{more fields for internal use} 
END; 
TPRect = “Rect; 
TPrStatus = RECORD 
iTotPages: INTEGER; {number of pages in spool file} 
iCurPage: INTEGER; {page being printed} 
iTotCopies: INTEGER; {number of copies requested} 
iCurCopy: INTEGER; {copy being printed} 
iTotBands: INTEGER; {used internally} 
iCurBand: INTEGER; {used internally} 
fPgDirty: BOOLEAN; {TRUE if started printing page} 
fImaging: BOOLEAN; {used internally} 
hPrint: THPrint; {print record} 
pPrPort: TPPrPort; {printing grafPort} 
hPic: PicHandle {used internally} 
END; 
TGnlData = RECORD 
{1st 8 bytes are common for all PrGeneral calls); 
i0pCode: Integer; {input} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 


{more fields here, depending on particular call} 
END; 


{used in TGetRslBlk} 
{0 if printer supports only discrete resolutions} 
{0 if printer supports only discrete resolutions} 


TRslRg = RECORD 
iMin: 
iMax: 


Integer; 
Integer; 
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ry 


END; 


TRslRec = RECORD {used in TGetRslBlk} 
iXRsl: Integer; {a discrete, physical X resolution} 
iYRsl: Integer; {a discrete, physical Y resolution} 


END; 
TGetRslBlk = RECORD {data block for GetRslData call} 
i0pCode: Integer; {input; = getRslData0p} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
iRgType: Integer; {output; version number} 
XRslRg: TRslRg; {output; range of X resolutions} 
YRslRg: TRslRg; {output; range of Y resolutions} 
iRslRecCnt: Integer; {output; how many RslRecs follow} 


rgRslRec: ARRAY[1..27] OF TRslRec; {output; number filled } 
{ depends on printer type} 


END; 
TSetRslBlk = RECORD {data block for SetRsl call} 
i0pCode: Integer; {input; = setRslOp} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
hPrint: THPrint; f{input; handle to a valid print record} 
iXRslL: Integer; {input; desired X resolution} 
iYRsL: Integer; {input; desired Y resolution} 
END; 
TDftBitsBlk = RECORD {data block for DraftBits and } 
{ NoDraftBits calls} 
i0pCode: Integer; {input; = draftBitsOp or noDraftBitsOp} 
iError: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
hPrint: THPrint; f{input; handle to a valid print record} 
END; 
TGetRotnBlk = RECORD {data block for GetRotn call} 
i0pCode: Integer; {input; = getRotnOp} 
iError: Integer; {output} 
LlReserved: LongInt; {reserved for future use} 
hPrint: THPrint; {input; handle to a valid } 
{ print record} 
flandscape: Boolean; f{output; Boolean flag} 
bXtra: SignedByte; {reserved} 
END; 
Routines 


PROCEDURE PrOpen; 

PROCEDURE PrClose; 

PROCEDURE PrintDefault (hPrint: THPrint); 

FUNCTION PrValidate (hPrint: THPrint) : Boolean; 
FUNCTION PrStlDialog (hPrint: THPrint) : Boolean; 
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FUNCTION 
PROCEDURE 
FUNCTION 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


FUNCTION 

PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


FUNCTION 
FUNCTION 
PROCEDURE 


PrjJobDialog 
PrjobMerge 
PrOpenDoc 


PrCloseDoc 
PrOpenPage 
PrClosePage 
PrPicFile 


PrError: 
PrSetError 
PrDrvrOpen; 
PrDrvrClose; 
PrctlCall 


PrDrvrDCE: 
PrDrvrVers: 
PrGeneral 


(hPrint: THPrint) : Boolean; 

(hPrintSrc, hPrintDst: THPrint); 
(hPrint: THPrint; pPrPort: TPPrPort; 
plOBuf: Ptr): TPPrPort; 

pPrPort: TPPrPort); 

pPrPort: TPPrPort; pPageFrame: TPRect); 
pPrPort: TPPrPort); 

hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: 
pDevBuf: Ptr; VAR PrStatus: TPrStatus) ; 
Integer; 

(iErr: Integer); 


( 
( 
( 
( 


(iWhichCtl: Integer; 

lParaml, lParam2, lParam3: LongInt); 
Handle; 

Integer; 

(pData: Ptr); 


Ptr; 


Assembly-Language Information 


Constants 
; Printing 


bDraftLoop 
bSpoolLoop 
» Result c 
noErr 
iPrSavPFil 
controlErr 
iI0Abort 
iMemFulLlEr 
iPrAbort 


methods 
. EQU 0 
. EQU 1 
odes 
. EQU 0 
. EQU -1 
.EQU  —17 
.EQU —27 
r .EQU —108 
.EQU 128 


;draft printing 
;Spool printing 


;no error 
;saving spool file 

;unimplemented control instruction 
;I/0 abort error 

;not enough room in heap zone 
;application or user requested abort 


; Printer Driver Control call parameters 


iPrDevCtl . EQU 
LPrReset . EQU 
iPrLineFeed . EQU 
iPrLFSixth . EQU 
LPrPageEnd .EQU 
iPrBitsCtl . EQU 
LScreenBits . EQU 
LPaintBits . EQU 
iPrIOctl . EQU 


. 
| 


OrROBNWWEHENA 


;printer control 

; reset printer 

; carriage return/paper advance 
;standard 1/6-inch line feed 

; end page 

;bit map printing 

; default for printer 

; square dots (72 by 72) 

;text streaming 


Printer Driver information 


iPrDrvrRef . EQU -3 ;Printer Driver reference number 
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Printing GrafPort Data Structure 


gPort GrafPort to draw in (portRec bytes) 
iPrPortSize Size in bytes of printing grafPort 


Print Record Data Structure 


iPrVersion Printing Manager version (word) 

prinfo Printer information subrecord (14 bytes) 
rPaper Paper rectangle (8 bytes) 

prstl Additional device information (8 bytes) 
prXInfo Additional device information (16 bytes) 
prJob Job subrecord (iPrjJobSize bytes) 
iPrintSize Size in bytes of print record 


Structure of Printer Information Subrecord 

iVRes Vertical resolution of printer (word) 
iHRes Horizontal resolution of printer (word) 
rPage Page rectangle (8 bytes) 


Structure of Job Subrecord 


iFstPage First page to print (word) 

iLstPage Last page to print (word) 

iCopies Number of copies (word) 

bjJDocLoop Printing method (byte) 

pIdleProc Address of background procedure 

pFileName Pointer to spool file name (preceded by length byte) 
iFileVol Spool file volume reference number (word) 

bFileVers Spool file version number (byte) 


iPrJobSize Size in bytes of job subrecord 
Structure of PrXInfo Subrecord 
iDevBytes Size of buffer (word) 


Structure of Printer Status Record 


iTotPages Number of pages in spool file (word) 

iCurPage Page being printed (word) 

iTotCopies Number of copies requested (word) 

iCurCopy Copy being printed (word) 

fPgDirty Nonzero if started printing page (byte) 

hPrint Handle to print record 

pPrPort Pointer to printing grafPort 

iPrStatSize Size in bytes of printer status record 

Variables 

PrintErr Result code from last Printing Manager routine (word) 
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Further Reference: 


Resource Manager 

QuickDraw 

Dialog Manager 

Device Manager 

Technical Note #33, ImageWriter II Paper Motion 

Technical Note #72, Optimizing for the LaserWriter — Techniques 
Technical Note #73, Color Printing 

Technical Note #91, Optimizing for the LaserWriter—Picture Comments 
Technical Note #92, The Appearance of Text 

Technical Note #95, How To Add Items to the Print Dialogs 

Technical Note #118, How to Check and Handle Printing Errors 
Technical Note #122, Device-Independent Printing 

Technical Note #123, Bugs in LaserWriter ROMs 

Technical Note #124, Low-Level Printing Calls With AppleTalk ImageWriters 
Technical Note #125, Effect of Spool-a-page/Print-a-page on Shared Printers 
Technical Note #128, PrGeneral 

Technical Note #133, Am I Talking To A Spooler? 

Technical Note #149, Document Names and the Printing Manager 
Technical Note #152, Using Laser Prep Routines 

Technical Note #161, When to Call PrOpen and PrClose 

Technical Note #173, PrGeneral Bug 

Technical Note #175, SetLineWidth Revealed 

Technical Note #183, Position-Independent PostScript 

Technical Note #192, Surprises in LaserWriter 5.0 and newer 
Technical Note #217, Where Have My Font Icons Gone? 

"Apple LaserwWriter Reference" 


END OF DOCUMENT 
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